<!DOCTYPE html SYSTEM "about:legacy-compat">
<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="../images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Catalina Functional Specifications (8.0.36) - Administrative Apps - Overall Requirements</title><meta name="author" content="Craig McClanahan"><script type="application/javascript" data-comments-identifier="tomcat-8.0-doc/funcspecs/fs-admin-apps">
    "use strict"; // Enable strict mode

    (function() {
      var thisScript = document.currentScript;
      if (!thisScript) { // Workaround for IE <= 11
        var scripts = document.getElementsByTagName("script");
        thisScript = scripts[scripts.length - 1];
      }
      document.addEventListener("DOMContentLoaded", (function() {
        var commentsDiv = document.getElementById("comments_thread");
        var commentsShortname = "tomcat";
        var commentsIdentifier = "http://tomcat.apache.org/" +
          thisScript.getAttribute("data-comments-identifier") + ".html";

        (function(w, d) {
          if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
            var s = d.createElement("script");
            s.type = "application/javascript";
            s.async = true;
            s.src = "https://comments.apache.org/show_comments.lua?site=" +
              encodeURIComponent(commentsShortname) +
              "&page=" + encodeURIComponent(commentsIdentifier);
            d.head.appendChild(s);
          } else {
            commentsDiv.appendChild(d.createTextNode("Comments are disabled for this page at the moment."));
          }
        })(window, document);
      }), false);
    })();
  </script></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="http://tomcat.apache.org/"><img alt="Tomcat Home" src="../images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="http://www.apache.org/" target="_blank"><img src="../images/asf-feather.png" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Catalina Functional Specifications</h1><div class="versionInfo">
          Version 8.0.36,
          <time datetime="2016-06-09">Jun 9 2016</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Functional Specs</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul></div><div><h2>Administrative Apps</h2><ul><li><a href="fs-admin-apps.html">Overall Requirements</a></li><li><a href="mbean-names.html">Tomcat MBean Names</a></li><li><a href="fs-admin-objects.html">Administered Objects</a></li><li><a href="fs-admin-opers.html">Supported Operations</a></li></ul></div><div><h2>Internal Servlets</h2><ul><li><a href="fs-default.html">Default Servlet</a></li></ul></div><div><h2>Realm Implementations</h2><ul><li><a href="fs-jdbc-realm.html">JDBC Realm</a></li><li><a href="fs-jndi-realm.html">JNDI Realm</a></li><li><a href="fs-memory-realm.html">Memory Realm</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>Administrative Apps - Overall Requirements</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
<ul><li><a href="#Overview">Overview</a><ol><li><a href="#Introduction">Introduction</a></li><li><a href="#External_Specifications">External Specifications</a></li><li><a href="#Implementation_Requirements">Implementation Requirements</a></li></ol></li><li><a href="#Dependencies">Dependencies</a><ol><li><a href="#Environmental_Dependencies">Environmental Dependencies</a></li><li><a href="#Container_Dependencies">Container Dependencies</a></li><li><a href="#External_Technologies">External Technologies</a></li></ol></li><li><a href="#Functionality">Functionality</a><ol><li><a href="#Properties_of_Administered_Objects">Properties of Administered Objects</a></li><li><a href="#Supported_Administrative_Operations">Supported Administrative Operations</a></li><li><a href="#Access_Method_Specific_Requirements">Access Method Specific Requirements</a></li></ol></li><li><a href="#Testable_Assertions">Testable Assertions</a></li></ul>
</div><h3 id="Overview">Overview</h3><div class="text">


  <div class="subsection"><h4 id="Introduction">Introduction</h4><div class="text">

    <p>The purpose of this specification is to define high level requirements
    for administrative applications that can be used to manage the operation
    of a running Tomcat container.  A variety of <em>Access Methods</em>
    to the supported administrative functionality shall be supported, to
    meet varying requirements:</p>
    <ul>
    <li><em>As A Scriptable Web Application</em> - The existing
        <code>Manager</code> web application provides a simple HTTP-based
        interface for managing Tomcat through commands that are expressed
        entirely through a request URI.  This is useful in environments
        where you wish to script administrative commands with tools that
        can generate HTTP transactions.</li>
    <li><em>As An HTML-Based Web Application</em> - Use an HTML presentation
        to provide a GUI-like user interface for humans to interact with the
        administrative capabilities.</li>
    <li><em>As SOAP-Based Web Services</em> - The operational commands to
        administer Tomcat are made available as web services that utilize
        SOAP message formats.</li>
    <li><em>As Java Management Extensions (JMX) Commands</em> - The operational
        commands to administer Tomcat are made available through JMX APIs,
        for integration into management consoles that utilize them.</li>
    <li><em>Other Remote Access APIs</em> - Other remote access APIs, such
        as JINI, RMI, and CORBA can also be utilized to access administrative
        capabilities.</li>
    </ul>

    <p>Underlying all of the access methods described above, it is assumed
    that the actual operations are performed either directly on the
    corresponding Catalina components (such as calling the
    <code>Deployer.deploy()</code> method to deploy a new web application),
    or through a "business logic" layer that can be shared across all of the
    access methods.  This approach minimizes the cost of adding new
    administrative capabilities later -- it is only necessary to add the
    corresponding business logic function, and then write adapters to it for
    all desired access methods.</p>

    <p>The current status of this functional specification is
    <strong>PROPOSED</strong>.  It has not yet been discussed and
    agreed to on the TOMCAT-DEV mailing list.</p>

  </div></div>


  <div class="subsection"><h4 id="External_Specifications">External Specifications</h4><div class="text">

    <p>The implementation of this functionality depends on the following
    external specifications:</p>
    <ul>
    <li><a href="http://docs.oracle.com/javase/7/docs/technotes/guides/idl">
        Java IDL</a> (for CORBA, included in the JDK)</li>
    <li><a href="http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html">
        Java Management Extensions</a></li>
    <li><a href="http://docs.oracle.com/javase/7/docs/technotes/guides/rmi">
        Remote Method Invocation</a> (Included in the JDK)</li>
    </ul>

  </div></div>


  <div class="subsection"><h4 id="Implementation_Requirements">Implementation Requirements</h4><div class="text">

    <p>The implementation of this functionality shall conform to the
    following requirements:</p>
    <ul>
    <li>To the maximum extent feasible, all administrative functions,
        and the access methods that support them, shall run portably
        on all platforms where Tomcat itself runs.</li>
    <li>In a default Tomcat distribution, all administrative capabilities
        shall be disabled.  It shall be necessary for a system
        administrator to specifically enable the desired access methods
        (such as by adding a username/password with a specific role to
        the Tomcat user's database.</li>
    <li>Administrative functions shall be realized as direct calls to
        corresponding Catalina APIs, or through a business logic layer
        that is independent of the access method used to initiate it.</li>
    <li>The common business logic components shall be implemented in
        package <code>org.apache.catalina.admin</code>.</li>
    <li>The common business logic components shall be built as part of the
        standard Catalina build process, and made visible in the
        Catalina class loader.</li>
    <li>The Java components required for each access method shall be
        implemented in subpackages of <code>org.apache.catalina.admin</code>.
        </li>
    <li>The build scripts should treat each access method as optional,
        so that it will be built only if the corresponding required
        APIs are present at build time.</li>
    <li>It shall be possible to save the configured state of the running
        Tomcat container such that this state can be reproduced when the
        container is shut down and restarted.</li>
    <li>Administrative commands to start up and shut down the overall
        Tomcat container are <strong>out of scope</strong> for the
        purposes of these applications.  It is assumed that other
        (usually platform-specific) mechanisms will be used for container
        startup and shutdown.</li>
    </ul>

  </div></div>


</div><h3 id="Dependencies">Dependencies</h3><div class="text">


  <div class="subsection"><h4 id="Environmental_Dependencies">Environmental Dependencies</h4><div class="text">

    <p>The following environmental dependencies must be met in order for
    administrative applications to operate correctly:</p>
    <ul>
    <li>For access methods that require creation of server sockets, the
        appropriate ports must be configured and available.</li>
    </ul>

  </div></div>


  <div class="subsection"><h4 id="Container_Dependencies">Container Dependencies</h4><div class="text">

    <p>Correct operation of administrative applications depends on the
       following specific features of the surrounding container:</p>
    <ul>
    <li>To the maximum extent feasible, Catalina components that offer
        direct administrative APIs and property setters shall support
        "live" changes to their operation, without requiring a container
        restart.</li>
    </ul>

  </div></div>


  <div class="subsection"><h4 id="External_Technologies">External Technologies</h4><div class="text">

    <p>The availability of the following technologies can be assumed
    for the implementation and operation of the various access methods
    and the corresponding administrative business logic:<br>
    <strong>FIXME</strong> - This list below is totally outdated, but nobody
    cares about the administrative app anymore. It is removed and unsupported
    since Tomcat 6.0.</p>
    <ul>
    <li><a href="http://www.oracle.com/technetwork/java/javase/overview/index.html">
        Java Standard Edition</a> (Version 1.2 or later)</li>
    <li><a href="http://www.jcp.org/jsr/detail/154.jsp">Servlet 2.4</a>
        (supported natively by Tomcat 5)</li>
    <li><a href="http://www.jcp.org/jsr/detail/152.jsp">JavaServer Pages 2.0</a>
        (supported natively by Tomcat 5)</li>
    <li><a href="http://jakarta.apache.org/taglibs/doc/standard-doc/intro.html">JavaServer Pages Standard Tag Library 1.0 (Jakarta Taglibs-Standard 1.0.3)</a></li>
    <li><a href="http://struts.apache.org/">Struts Framework</a>
        (Version 1.0) - MVC Framework for Web Applications</li>
    <li><strong>TO BE DETERMINED</strong> - Application for hosting SOAP
        based web services</li>
    </ul>

  </div></div>


</div><h3 id="Functionality">Functionality</h3><div class="text">


  <div class="subsection"><h4 id="Properties_of_Administered_Objects">Properties of Administered Objects</h4><div class="text">

  <p>Functional requirements for administrative applications are specified
  in terms of <em>Administered Objects</em>, whose definitions and detailed
  properties are listed <a href="fs-admin-objects.html">here</a>.  In general,
  Administered Objects correspond to components in the Catalina architecture,
  but these objects are defined separately here for the following reasons:</p>
  <ul>
  <li>It is possible that the administrative applications do not expose
      every possible configurable facet of the underlying components.</li>
  <li>In some cases, an Administered Object (from the perspective of an
      administrative operation) is realized by more than one Catalina
      component, at a finer-grained level of detail.</li>
  <li>It is necessary to represent the configuration information for a
      component separately from the component itself (for instance, in
      order to store that configuration information for later use).</li>
  <li>It is necessary to represent configuration information (such as
      a Default Context) when there is no corresponding component instance.
      </li>
  <li>Administered Objects, when realized as Java classes, will include
      methods for administrative operations that have no correspondence
      to operations performed by the corresponding actual components.</li>
  </ul>

  <p>It is assumed that the reader is familiar with the overall component
  architecture of Catalina.  For further information, see the corresponding
  Developer Documentation.  To distinguish names that are used as both
  <em>Administered Objects</em> and <code>Components</code>, different
  font presentations are utilized.  Default values for many properties
  are listed in [square brackets].</p>

  </div></div>


  <div class="subsection"><h4 id="Supported_Administrative_Operations">Supported Administrative Operations</h4><div class="text">

  <p>The administrative operations that are available are described in terms
  of the corresponding Administered Objects (as defined above), in a manner
  that is independent of the access method by which these operations are
  requested.  In general, such operations are relevant only in the context
  of a particular Administered Object (and will most likely be realized as
  method calls on the corresponding Administered Object classes), so they
  are organized based on the currently "focused" administered object.
  The available Supported Operations are documented
  <a href="fs-admin-opers.html">here</a>.</p>

  </div></div>


  <div class="subsection"><h4 id="Access_Method_Specific_Requirements">Access Method Specific Requirements</h4><div class="text">

  <h5>Scriptable Web Application</h5>

  <p>An appropriate subset of the administrative operations described above
  shall be implemented as commands that can be performed by the "Manager"
  web application.  <strong>FIXME</strong> - Enumerate them.</p>

  <p>In addition, this web application shall conform to the following
  requirements:</p>
  <ul>
  <li>All request URIs shall be protected by security constraints that
      require a security role to be assigned for processing.</li>
  <li>The default user database shall <strong>not</strong> contain any
      user that has been assigned a security role.</li>
  </ul>

  <h5>HTML-Based Web Application</h5>

  <p>The entire suite of administrative operations described above shall be
  made available through a web application designed for human interaction.
  In addition, this web application shall conform to the following
  requirements:</p>
  <ul>
  <li>Must be implemented using servlet, JSP, and MVC framework technologies
      described under "External Technologies", above.</li>
  <li>Prompts and error messages must be internationalizable to multiple
      languages.</li>
  <li>Rendered HTML must be compatible with Netscape Navigator (version 4.7
      or later) and Internet Explorer (version 5.0 or later).</li>
  </ul>

  </div></div>


</div><h3 id="Testable_Assertions">Testable Assertions</h3><div class="text">

  <p><strong>FIXME</strong> - Complete this section.</p>

</div><div class="noprint"><h3 id="comments_section">
                  Comments
                </h3><div class="text"><p class="notice"><strong>Notice: </strong>This comments section collects your suggestions
                    on improving documentation for Apache Tomcat.<br><br>
                    If you have trouble and need help, read
                    <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
                    and ask your question on the tomcat-users
                    <a href="http://tomcat.apache.org/lists.html">mailing list</a>.
                    Do not ask such questions here. This is not a Q&amp;A section.<br><br>
                    The Apache Comments System is explained <a href="../comments.html">here</a>.
                    Comments may be removed by our moderators if they are either
                    implemented or considered invalid/off-topic.
                  </p><div id="comments_thread"></div></div></div></div></div></div></div><footer><div id="footer">
    Copyright &copy; 1999-2016, The Apache Software Foundation
  </div></footer></div></body></html>